<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tcl_CreateFileHandler manual page - Tcl Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl C API</a> <small>&gt;</small> CrtFileHdlr</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
Tcl_CreateFileHandler, Tcl_DeleteFileHandler &mdash; associate procedure callbacks with files or devices (Unix only)
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tcl.h&gt;</B><BR>
<B>Tcl_CreateFileHandler</B>(<I>fd, mask, proc, clientData</I>)<BR>
<B>Tcl_DeleteFileHandler</B>(<I>fd</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT>int <B>fd</B> (in)<DD>
Unix file descriptor for an open file or device.
<P><DT>int <B>mask</B> (in)<DD>
Conditions under which <I>proc</I> should be called:
OR-ed combination of <B>TCL_READABLE</B>, <B>TCL_WRITABLE</B>,
and <B>TCL_EXCEPTION</B>.  May be set to 0 to temporarily disable
a handler.
<P><DT>Tcl_FileProc <B>*proc</B> (in)<DD>
Procedure to invoke whenever the file or device indicated
by <I>file</I> meets the conditions specified by <I>mask</I>.
<P><DT>ClientData <B>clientData</B> (in)<DD>
Arbitrary one-word value to pass to <I>proc</I>.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
<B>Tcl_CreateFileHandler</B> arranges for <I>proc</I> to be
invoked in the future whenever I/O becomes possible on a file
or an exceptional condition exists for the file.  The file
is indicated by <I>fd</I>, and the conditions of interest
are indicated by <I>mask</I>.  For example, if <I>mask</I>
is <B>TCL_READABLE</B>, <I>proc</I> will be called when
the file is readable.
The callback to <I>proc</I> is made by <B><A HREF="../TclLib/DoOneEvent.htm">Tcl_DoOneEvent</A></B>, so
<B>Tcl_CreateFileHandler</B> is only useful in programs that dispatch
events through <B><A HREF="../TclLib/DoOneEvent.htm">Tcl_DoOneEvent</A></B> or through Tcl commands such
as <B><A HREF="../TclCmd/vwait.htm">vwait</A></B>.
<P>
<I>Proc</I> should have arguments and result that match the
type <B>Tcl_FileProc</B>:
<P>
<PRE>typedef void <B>Tcl_FileProc</B>(
        ClientData <I>clientData</I>,
        int <I>mask</I>);</PRE>
<P>
The <I>clientData</I> parameter to <I>proc</I> is a copy
of the <I>clientData</I>
argument given to <B>Tcl_CreateFileHandler</B> when the callback
was created.  Typically, <I>clientData</I> points to a data
structure containing application-specific information about
the file.  <I>Mask</I> is an integer mask indicating which
of the requested conditions actually exists for the file;  it
will contain a subset of the bits in the <I>mask</I> argument
to <B>Tcl_CreateFileHandler</B>.
<P>
There may exist only one handler for a given file at a given time.
If <B>Tcl_CreateFileHandler</B> is called when a handler already
exists for <I>fd</I>, then the new callback replaces the information
that was previously recorded.
<P>
<B>Tcl_DeleteFileHandler</B> may be called to delete the
file handler for <I>fd</I>;  if no handler exists for the
file given by <I>fd</I> then the procedure has no effect.
<P>
The purpose of file handlers is to enable an application to respond to
events while waiting for files to become ready for I/O.  For this to work
correctly, the application may need to use non-blocking I/O operations on
the files for which handlers are declared.  Otherwise the application may
block if it reads or writes too much data; while waiting for the I/O to
complete the application will not be able to service other events. Use
<B><A HREF="../TclLib/OpenFileChnl.htm">Tcl_SetChannelOption</A></B> with <B>-blocking</B> to set the channel into
blocking or nonblocking mode as required.
<P>
Note that these interfaces are only supported by the Unix
implementation of the Tcl notifier.
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/fileevent.htm">fileevent</A></B>, <B><A HREF="../TclLib/CrtTimerHdlr.htm">Tcl_CreateTimerHandler</A></B>, <B><A HREF="../TclLib/DoWhenIdle.htm">Tcl_DoWhenIdle</A></B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/C.htm#callback">callback</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/H.htm#handler">handler</A>
<div class="copy">Copyright &copy; 1990-1994 The Regents of the University of California.
<BR>Copyright &copy; 1994-1997 Sun Microsystems, Inc.
</div>
</BODY></HTML>
